\chapter{Introduction}

\section{Document purpose} 
This document is the proposal for the 'Mobile Applications' module project and therefore part of the module assessment.
The document supplies the lecturer with information about the project idea and solution statement.

\section{Document correlation}
The project documentation document and the project proposal document relate to each other.

\chapter{General description}

\section{Project purpose}
The main goal of the project is the porting of the card game Pairs for Android smartphone.
User can select different Pairs games and play with each other on the same smartphone device.

\section{Requirements analysis}

The requirements are derived from the game rules (see section \ref{sec:GameExplanation}) and 
from some Pairs app descriptions on the Google play store \cite{AppStore14Pairs}.
The Google play store offers a large amount of different Pairs games, 
because Pairs is a mini game and is also very popular in several countries.

All suggested apps contain the functionality to play the game Pairs. 
Some of them allow multiplayer matches on one smartphone and display additional information about the game status.
Most of the reviewed apps offer the possibility to manage different games.
The price of the games vary between zero and one pound, but most of them are for free.
\cite{GooglePlay14MemoryPairs1} \cite{GooglePlay14MemoryPairs2} \cite{GooglePlay14Pairs1} \cite{GooglePlay14Pairs2}

The functionality of the Google play store apps, reflect the basic requirements for the game rules.
Therefore all of the above features are important for the game implementation and 
are part of the project application requirements. 

From this it follows that, the new Pairs app needs a view to manage several different games.
Furthermore the app has to offer a game view to play multiplayer matches on one smartphone.
The game view should display additional information about the game status.


\section{Functionality}
The following functionality is subject of the implementation.


\subsection{Priority features}
The smartphone application offers a multiplayer mode for two players.
The game view contains the visualisation of the game board and provides score information for both players, 
as well as which players turn it is.

In addition, the application also provides the possibility to administer different Pairs games. 
The administration view contains information about the name of the game, the date and the location data in a list representation.

A more detailed view shows the information about a single Pairs game. This view is also for the editing of the game name and
to display the entire cards set.


\subsection{Optional features}
Depending on the guidelines of the lecturer and the resulting workload, 
an \textbf{optional} feature can be the digitalisation of physical Pairs games.
The digitalisation view provides a possibility to store physical Pairs games, by taking a photo and image editing, 
with minimal user support.

This feature could be the unique selling point, compared to the reviewed games from the Google play store.

\newpage

\section{Hard- and software restrictions}

The development of the smartphone app concentrates on gaining practice and 
therefore will only be tested on one device (LG Nexus 5 \cite{Hardware14Nexus5}) and on an Android emulator.

Android 4.4 KitKat is the target operating system, because it is the latest Android version on project start and 
serves the largest part of the android users \cite{Software14ApiLevel}. 
Therefore the \acs{API} level is 19.
To target only one version of the Android operating system, also simplifies the development, 
because it is not necessary to deal with several ways of implementation for different Android versions.

\begin{figure}[htbp]
  \centering 
    \includegraphics[width=11cm]{chapter1/ApiLevelDiagram}
    \caption{API level distribution on September 9, 2014 \cite{Software14ApiLevel} \cite{Chart14Pie}}
    \label{fig:ApiLevel}
\end{figure} 

For the optional feature, the app relies on a camera to take pictures.


\section{Target Audience}

The target audience for the finished Pairs app are enthusiasts of the cards game Pairs 
which are in possession of a updated Android smartphone.
Especially those who have to travel a lot and do not want to give up of their Pairs passion, because of transport problems.

Enthusiasts of the game Pairs like to play their favorite set of card motives.

\newpage

\chapter{Detailed description}

\section{Game explanation}
\label{sec:GameExplanation}

The following information refers to the game in general, 
respectively the rules and should give a brief insight for those how do not know the game yet.

The game "Pairs", "Memory" or also known as "Concentration", is a card game about concentration for the whole family 
(see figure \ref{fig:memoryBox}). 
It is possible to play Pairs as single player or with several players.
The play time depends on the amount of cards but regularly is about thirty minutes.
Usually the game consists of more than twenty-four square cardboard cards.
The back of all the cards looks identical (see figure \ref{fig:memoryBack}).
Each card has a motive on the front, for example a picture or a pattern.
There are always two cards with the same motive at the front (see figure \ref{fig:memoryPair}). 
\cite{Arneson14Rules}  \cite{BoardGame14Info}

\begin{figure}[htbp]
  \centering
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryBox}
    \caption{Box \\ \cite{Memory14Box}}
    \label{fig:memoryBox}
  \end{subfigure}%
  ~~~~~~~~~~~~ %add desired spacing between images, e. g. ~, \quad, \qquad, \hfill etc.
    %(or a blank line to force the subfigure onto a new line)
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryBack}
    \caption{Back side \\ \cite{Memory14Back}}
    \label{fig:memoryBack}
  \end{subfigure}
  ~~~~~~~~~~~~ %add desired spacing between images, e. g. ~, \quad, \qquad, \hfill etc.
    %(or a blank line to force the subfigure onto a new line)
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryPair}
    \caption{A pair \\ \cite{Memory14Pair}}
    \label{fig:memoryPair}
  \end{subfigure}
   ~~~~~~~~~~~~ %add desired spacing between images, e. g. ~, \quad, \qquad, \hfill etc.
    %(or a blank line to force the subfigure onto a new line)
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryOverlap}
    \caption{No overlapping \\ \cite{Memory14Overlap}} 
    \label{fig:memoryOverlap}
  \end{subfigure}
  \caption{Box and content}\label{fig:boxAndContent}
\end{figure}
 
\subsection{Game setup}

To prepare a new game, take all cards out of the box and shuffle them. 
During shuffling, the cards remain with the back side upwards to prevent cheating.
Afterwards, place all cards subsurface on a flat space.
From now on, this flat space with the cards on it, is the game board.
Leave the positioning of the cards arbitrarily (see figure \ref{fig:memoryArbitrarily})
or arrange them according to a pattern (see figure \ref{fig:memoryPattern}), but make sure
that there are no cards overlap (see figure \ref{fig:memoryOverlap}). 
\cite{Arneson14Rules} 

\begin{figure}[htbp]
  \centering
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryArbitrarily}
    \caption{Arbitrarily \\ \cite{Memory14Arbitrarily}}
    \label{fig:memoryArbitrarily}
  \end{subfigure}%
  ~~~~~~~~~~~~ %add desired spacing between images, e. g. ~, \quad, \qquad, \hfill etc.
    %(or a blank line to force the subfigure onto a new line)
  \begin{subfigure}[b]{0.27\textwidth}
    \includegraphics[width=\textwidth]{chapter1/memoryPattern}
    \caption{Pattern \\ \cite{Memory14Pattern}}
    \label{fig:memoryPattern}
  \end{subfigure}
  \caption{Positioning}\label{fig:positioning}
\end{figure}

\subsection{Game play}

Usually, the loser starts.
If there is no loser yet, the youngest player goes first.
The current player uncovers two arbitrary cards.
If both cards show the same motive, the current player takes these two cards, gains one Point and can uncovers two other cards.
If both cards show different motives, the current player waits for all other players to see these cards and covers both cards again.
It is the next players turn. \cite{Arneson14Rules}

\subsection{Goal}

The goal is to collect the most pairs of cards.
If there are no cards left on the game board, the player with the most points (most card-pairs) wins the game.

\newpage

\section{Features}

The following explanations and figures refer to the implementation approach.
The smartphone app has to cover most of the scenarios from the section \ref{sec:GameExplanation}.

All following mock-ups are just design suggestions. 
The finished app \acs{GUI} might look slightly different, because of design limitations.


\subsection{Priority features}

The mock-up depicts the administration view and the game view (see figure \ref{fig:mockUp01}).
The arrow describes the user-driven change between the different views.
Player A and player B are represented by the two hand contours.

\begin{figure}[htbp]
  \centering
    \includegraphics[width=\textwidth]{chapter1/mockUp01}
    \caption{Mock-up administration view and game view}
    \label{fig:mockUp01}
\end{figure} 

The application starts in the administration view with a list of all existing Pairs games.
Each list entry contains at least the name of the game and a preview image 
(a thumbnail as representative for the whole cards set).
It is possible to navigate to hidden games at the end of the list, with swipe-gestures.

If a user touches a list entry, the \acs{App} changes to the game view for the multiplayer game.
This view represents the game board and contains the set of pair cards, as well as information about the score.
At the beginning of a new game, all cards remain subsurface.
The player who starts selects and touches a card to uncover it.
Afterwards, he can touch a second card to uncover it.
Both cards get automatically covered after a certain time.
The arbitrary arrangement of the cards is not intended for now
(just pattern orientated arrangement of the cards is possible).

\newpage

At the end of the game, a dialog declares the winner and the app changes to the administration view.

During the ongoing game, both players facing each other, while the smartphone resides between them.




% TODO: Beschreiben was man auf dem Bild gerade sieht 
% TODO: Beschreiben was ich mir dabei gedacht habe, evtl. auch welche Lerninhalte damit abgedeckt werden sollen.
% TODO: Ablauf des Spiels als UML Diagramm in Doku.. sieht professionell aus und kann in Bezug zu Code-Schnipsel stehenaussieht

\subsection{Optional features}

The mock-up depicts the digitalisation view and the overview view (see figure \ref{fig:mockUp02}).
The arrows describe the order of steps during the user-based digitalisation process.
User support for the digitalisation process is represented by the hand contours.

\begin{figure}[htbp]
  \centering
    \includegraphics[width=\textwidth]{chapter1/mockUp02} 
    \caption{Mock-up digitalisation view}
    \label{fig:mockUp02}
\end{figure} 

If a user touches the list entry to add a new game, 
the app changes to an introduction to help the user with the digitalisation process.
At first, the user looks for one card of each pair and arranges them in a rectangle shape, face upwards.
After this preparation the app changes to the on-board camera application to take a picture of the cards set.

Back from the camera view, the app shows the most top-left part of the picture to the user.
The user selects the four corners of the most top-left card.
Next, the user selects the top right hand corner and finally the bottom left hand corner of the rectangle shape of cards.
With the marks, it is possible to automatically cut the important part of the photo into a set of card pieces, 
which represent the new Pairs game.

The overview view contains information about the new game. 
Possible information are the name, the location, the date and the time.
The view also provides the digitalised set of cards.

There is a wide range of different Pairs games with a lot of different sets of motives.
For example sets about animals, persons, cars, flowers or even own sets of cards with customized motives.
This optional feature is interesting for the enthusiasts, that like to play their favorite set of card motives and
are able to digitalis these sets.

